Version: v25.03

KAE Operator

特性介绍

Kubernetes通过设备插件提供对特殊硬件资源（如鲲鹏KAE、NIC、Infiniband适配器和其他设备）的访问。但是配置和管理具有这些硬件资源的节点需要配置多个软件组件（如驱动程序、容器运行时或其他库），这些组件安装复杂困难且容易出错。 KAE Operator使用Kubernetes中的Operator Framework来自动管理配置KAE所需的所有软件组件。这些组件包括KAE驱动程序、KAE的Kubernetes设备插件。

鲲鹏加速引擎KAE（Kunpeng Accelerator Engine）是鲲鹏920系列处理器中携带的能力，具体请参见 KAE产品简介。

应用场景

KAE硬件加速：集群中业务使用KAE硬件加速能力（如加解密），KAE Operator可以自动识别集群中KAE节点和安装部署必要组件。

能力范围

自动发现KAE设备节点。
自动部署和配置KAE所有必要组件，以便在Kubernetes集群中高效使用KAE。
节点上设备变更时，自动调整组件，如设备下线时回收部署的服务。

亮点特征

KAE Operator自动管理配置KAE所需的所有软件组件，极大降低KAE硬件使用门槛，提高使用效率。

实现原理

Operator观察三种资源变化：

Operator自定义资源（CRD）发生变化。
集群中的节点发生变化（比如集群添加节点，集群节点的标签发生变化等）。
由Operator创建的Daemonsets发生变化。

Operator管理两类资源：

标签管理：根据NFD服务发现的系统、内核、硬件设备进行标签管理，给节点打印部署依赖的标签。
组件管理：根据CRD配置，组装资源文件安装服务。

Operator组件管理：

根据标签安装/卸载组件
升级/删除相关组件

与相关特性的关系

KAE Operator当前管理2个组件：

KAE Driver Installer：KAE驱动安装组件
KAE Device Plugin：KAE设备插件

图 1 KAE Operator实现原理

volcano

Operator的安全上下文

一些KAE Operator管理的Pod（例如驱动程序容器）需要提升的权限如下：

privileged: true
hostPID: true
hostIPC: true
hostNetwork: true

提升权限的原因如下：

访问主机文件系统和硬件设备，在宿主机上安装驱动。
修改设备权限，以适配非root用户使用。

只有Kubernetes集群管理员才需要访问或管理Operator命名空间。作为优秀实践，请用户建立适当的安全策略并阻止任何其他用户访问Operator命名空间。

安装

前提条件

计算机上有kubectl和Helm CLI或集群中有可配置的应用商店或仓库。
Kubernetes集群中运行KAE工作负载的所有工作节点或节点组都必须运行相同的操作系统版本（当前为openEuler 22.03 LTS）才能使用KAE驱动程序容器。

对于仅运行CPU工作负载的工作节点或节点组，节点可以运行任何操作系统，因为KAE Operator不会对非KAE工作负载的节点执行任何配置或管理。
KAE节点已激活License，具体操作参考KAE安装前准备。若为虚机场景，需要做好硬件切分和硬直通，具体操作参考KAE在虚拟机场景下的使用。
因驱动安装需要依赖kernel-devel等一些内核包，因此节点上要配置正确版本的yum源（操作系统和版本要求一致）。

离线环境时，可将系统镜像作为本地镜像源进行配置。如下仅为参考设置，使用时请用户根据实际情况配置。
- 请前往openEuler官网下载OS镜像，下载适用于服务器的标准版镜像（Offline Standard ISO）即可，要求下载镜像版本要与当前系统版本一致，完成下载后需将镜像文件上传至Linux环境，如上传至/mnt/iso目录下。
- 创建需要挂载的目录。
```
mkdir -p /mnt/openEuler
```
- 将镜像挂载到/mnt/openEuler目录下。
```
mount /mnt/iso/<OS镜像名字 eg: openEuler-22.03-LTS-x86_64-dvd.iso> /mnt/openEuler
```
- 配置yum源。
```
# 备份原有yum源
mv /etc/yum.repos.d/openEuler.repo /etc/yum.repos.d/openEuler.repo.bak
# 创建openEuler.repo文件
cat << EOF > /etc/yum.repos.d/openEuler.repo
[openEuler]
name=openEuler
baseurl=file:///mnt/openEuler
enabled=1
gpgcheck=1
gpgkey=file:///mnt/openEuler/RPM-GPG-KEY-openEuler
EOF
```
- 更新yum源缓存。
```
yum clean all
yum makecache
```
节点特性感知服务 (NFD) 是每个节点上Operator的依赖项。默认情况下，NFD主节点和工作节点由Operator自动部署。如果NFD已在集群中运行，则必须在安装Operator时禁用部署NFD。

values.yaml
```
nfd:
  enabled: false
```
确定NFD是否已在集群中运行的一种方法是检查节点上的NFD标签：
```
kubectl get nodes -o json | jq '.items[].metadata.labels | keys | any(startswith("feature.node.kubernetes.io"))'
```
如果命令输出为true，则NFD已在集群中运行。此时设置nodefeaturerules，安装KAE自定义节点发现规则。
```
nfd:
  nodefeaturerules: true
```

开始安装

openFuyao平台

KAE Operator扩展组件，可在openFuyao应用市场下载安装。

进入openFuyao平台，在左侧导航栏中选择“应用市场 > 应用列表”。
在应用列表搜索“kae operator”，找到KAE Operator扩展组件。
单击KAE Operator卡片进入应用的详情页。
在详情页单击右上角的“部署”，在部署界面的“安装信息”模块中输入“应用名称”，“版本信息”和“命名空间”。
单击“确认”，即可成功部署该组件。

通用场景

安装步骤

添加openFuyao Helm存储库：

helm repo add openfuyao https://harbor.openfuyao.com/chartrepo/openfuyao-catalog \
    && helm repo update

安装KAE Operator。

使用默认配置安装Operator：

$ helm install --wait --generate-name \
    -n kae-operator --create-namespace \
    openfuyao/kae-operator

安装Operator并指定配置选项：

$ helm install --wait --generate-name \
    -n kae-operator --create-namespace \
    openfuyao/kae-operator \
    --set <option-name>=<option-value>

若基于Helm应用商店/市场方式安装，则通过添加https://harbor.openfuyao.com/chartrepo/openfuyao-catalog仓，在界面安装即可。详情请参见常见定制选项和常见部署场景。

常见定制选项

使用Helm Chart时，以下选项可用。这些选项可以--set在使用Helm安装时使用。

下表列出了最常用的选项。要查看所有选项，请运行helm show values openfuyao/kae-operator。

表 1 常用的选项

范围	描述	默认
`nfd.enabled`	部署节特性感知服务NFD，如果NFD已在集群中运行，则设置此变量为`false`。说明：若安装时为`ture`使用时尽量不要修改此字段为`false`，否则会导致卸载时NFD残留标签。	`true`
`nfd.nodefeaturerules`	设置为`true`时，安装NFD发现KAE设备规则CR。	`false`
`node-feature-discovery.image.repository`	NFD服务镜像地址。	`registry.k8s.io/nfd/node-feature-discovery`
`node-feature-discovery.image.pullPolicy`	NFD服务镜像拉取策略。	`IfNotPresent`
`node-feature-discovery.image.tag`	NFD服务镜像版本。	`v0.16.4`
`operator.enabledHPRE`	使能KAE HPRE设备管理功能，开启时会管理HPRE设备，集群中不需要关注此设备时，设置为`false`。	`true`
`operator.enabledSEC`	使能KAE SEC设备管理功能，开启时会管理SEC设备，集群中不需要关注此设备时，设置为`false`。当前版本Operator只处理HPRE设备插件，此字段为预留接口。	`false`
`operator.enabledZIP`	使能KAE ZIP设备管理功能，开启时会管理ZIP设备，集群中不需要关注此设备时，设置为`false`。当前版本Operator只处理HPRE设备插件，此字段为预留接口。	`false`
`operator.upgradeCRD`	Operator使用`pre-upgrade`Helm Hook来执行升级CRD。	`false`
`operator.cleanupCRD`	Operator使用`post-delete`Helm Hook来执行清理CRD。	`false`
`operator.image`	KAE Operator镜像地址。	`harbor.openfuyao.com/openfuyao/kae-operator`
`operator.version`	KAE Operator镜像版本。	`latest`
`operator.pullPolicy`	KAE Operator镜像拉取策略。	`IfNotPresent`
`daemonSets.labels`	要添加到所有KAE Operator管理Pod的自定义标签。	`{}`
`daemonSets.tolerations`	要添加到所有KAE Operator管理Pod的自定义容忍。	`[]`
`driver.enabled`	默认情况下，Operator会将KAE驱动程序作为容器部署在系统上。在预装驱动程序的系统上使用Operator时，请将此值设置为`false`，Operator会卸载掉已安装的Driver DaemonSet（若存在）。说明：修改此字段为`false`时，其他同时设置的字段不生效。	`true`
`driver.enabledCleanup`	默认情况下，Operator卸载时或Driver DaemonSet销毁时，宿主机上的驱动程序不会卸载。若要同时卸载宿主机上的驱动程序时，请将此值设置为`true`。	`false`
`driver.repository`	驱动程序镜像存储库。使用自定义驱动程序镜像时请指定另一个镜像存储库。	`harbor.openfuyao.com/openfuyao`
`driver.image`	驱动程序镜像名称。若`driver.repository`和`driver.version`都为空，该字段请设置镜像全路径。	`kae-driver-installer`
`driver.version`	驱动程序版本。	`latest`
`driver.env`	驱动程序环境变量。当前支持安装策略KEY`INSTALL_POLICY`。值`IfNotPresent`：节点上已有驱动不覆盖；值`Always`：先卸载已有驱动再安装。	`IfNotPresent`
`devicePlugin.enabled`	默认情况下，Operator会将KAE设备插件程序部署在系统上。在预装设备插件的系统上使用Operator时，请将此值设置为`false`，Operator会卸载掉已安装的Device Plugin DaemonSet（若存在）。说明：修改此字段为`false`时，其他同时设置的字段不生效。	`true`
`devicePlugin.repository`	设备插件程序镜像存储库。使用自定义驱动程序镜像时请指定另一个镜像存储库。	`harbor.openfuyao.com/openfuyao`
`devicePlugin.image`	设备插件程序镜像名称。若`driver.repository`和`driver.version`都为空，该字段请设置镜像全路径。	`kae-device-plugin`
`devicePlugin.version`	设备插件程序版本。	`latest`
`psa.enabled`	如果集群使用Pod Security Admission (PSA) 来限制Pod的行为，请设置为`true`。	`false`

常见部署场景

以下常见部署场景和示例命令适合具有KAE直通的主机或虚拟机。

指定运算符命名空间

Operator命名空间是可配置的，在安装期间指定。例如，要在openfuyao命名空间中安装KAE Operator：

helm install --wait --generate-name \
     -n openfuyao --create-namespace \
     openfuyao/kae-operator

如果安装时不指定命名空间，则所有KAE Operator组件都会安装在该default命名空间中。

阻止在某些节点上安装KAE驱动程序

默认情况下，KAE Operator会在集群中的所有KAE工作节点上部署驱动程序。为了防止在KAE工作节点上安装驱动程序，请像以下示例命令一样标记该节点。

kubectl label nodes $NODE openfuyao.com/kae.deploy.driver=false

说明：

建议在安装KAE Operator前完成标签设置。

若节点重启或设备卸载后又添加请再次执行此命令。

若后续需要在此节点安装驱动程序，请执行kubectl label nodes $NODE openfuyao.com/kae.deploy.driver=true。

预安装KAE驱动程序

在具有KAE的工作节点上已安装KAE驱动程序时，则不需要KAE Operator管理驱动程序，设置：

helm install --wait --generate-name \
     -n kae-operator --create-namespace \
     openfuyao/kae-operator \
     --set driver.enabled=false

运行自定义镜像

通过覆盖helm install命令中的缺省值来指定新的镜像和存储库。例如：

helm install --wait --generate-name \
     -n kae-operator --create-namespace \
     openfuyao/kae-operator \
     --set driver.repository=docker.io/your repository \
     --set driver.version="0.1"

升级

KAE Operator支持对现有资源进行动态更新。此功能使KAE Operator能够确保集群中KAE Policy的设置始终保持最新。

由于Helm不支持现有CRD的自动升级，因此可以手动或通过启用Helm Hook来升级KAE Operator Chart。

手动升级CRD

在环境变量中指定Operator发布标签：
```
export RELEASE_TAG=v24.09
```

更新KAE Policy CRD：

kubectl apply -f <path>/device.openfuyao.com_kaepolicies_crd.yaml

输出示例

customresourcedefinition.apiextensions.k8s.io/kaepolicies.device.openfuyao.com configured

更新节点特性感知服务NFD的自定义资源定义：

kubectl apply -f <path>/nfd-api-crds.yaml

输出示例

customresourcedefinition.apiextensions.k8s.io/nodefeaturerules.nfd.k8s-sigs.io configured

更新Operator Chart的相关信息：

helm repo update openfuyao

输出示例

Hang tight while we grab the latest from your chart repositories...
...Successfully got an update from the "openfuyao" chart repository
Update Complete. ⎈Happy Helming!⎈

从Chart中获取values值：

helm show values openfuyao/kae-operator --version=$RELEASE_TAG > values-$RELEASE_TAG.yaml

根据需要更新文件。

升级Operator：

helm upgrade kae-operator openfuyao/kae-operator -n kae-operator -f values-$RELEASE_TAG.yaml

输出示例

Release "kae-operator" has been upgraded. Happy Helming!
NAME: kae-operator
LAST DEPLOYED: Thu sep 1 15:05:52 2024
NAMESPACE: kae-operator
STATUS: kae-operator
REVISION: 2
TEST SUITE: None

使用Helm Hook自动升级CRD

KAE Operator支持使用pre-upgradeHelm Hook自动升级CRD。参数operator.upgradeCRD用于在使用Helm升级KAE Operator期间触发此Hook。此功能默认禁用。在升级命令期间使用--set operator.upgradeCRD=true选项设置

在环境变量中指定Operator发布标签：
```
export RELEASE_TAG=v24.09
```

更新Operator Chart的相关信息：

helm repo update openfuyao

输出示例

Hang tight while we grab the latest from your chart repositories...
...Successfully got an update from the "openfuyao" chart repository
Update Complete. ⎈Happy Helming!⎈

从Chart中获取values值：

helm show values openfuyao/kae-operator --version=$RELEASE_TAG > values-$RELEASE_TAG.yaml

根据需要更新文件。
升级Operator：
```
helm upgrade kae-operator openfuyao/kae-operator -n kae-operator \
    --set operator.upgradeCRD=true --disable-openapi-validation -f values-$RELEASE_TAG.yaml
```
说明：
- 在这种情况下，需要设置选项 --disable-openapi-validation，以便Helm不会尝试验证新Chart的CR实例是否对旧CRD有效。由于Chart中的CR实例对升级后的CRD有效，因此这将是兼容的。
- Helm Hook使用的是Operator自身镜像。如果无法拉取镜像（可能是由于网络错误），Hook将失效。在这种情况下，需要使用--no-hooks选项删除Chart，以避免删除时Hook失败导致挂起。

KAE Policy CR更新

KAE Operator支持使用kubectl对KAEPolicyCustomResource进行动态更新：

kubectl edit kaepolicy kae-policy

编辑完成后，Kubernetes自动将应用更新到集群。

卸载

执行以下步骤来卸载Operator。

Helm CLI删除Operator或通过应用管理界面删除：

helm delete -n kae-operator $(helm list -n kae-operator | grep kae-operator | awk '{print $1}')

可选：列出Operator命名空间中的Pod，以确认Pod已被删除或正在删除：
```
kubectl get pods -n kae-operator
```
输出示例
```
No resources found.
```

默认情况下，Helm不支持在删除Chart时删除现有的CRD。

kubectl get crd kaepolicies.device.openfuyao.com

为了解决这个问题，Operator使用post-deleteHelm Hook来执行CRD清理。operator.cleanupCRD参数用来控制启用此Hook。默认情况下，此参数处于禁用状态。您可以在安装或升级期间指定--set operator.cleanupCRD=true启用此Hook，则在删除Chart时自动执行CRD清理。

或者，可以手动删除CRD：

kubectl delete crd kaepolicies.device.openfuyao.com

说明：
Operator卸载后驱动程序可能还存在于宿主机上。若要删除，请在卸载前，先更新values.yaml或kae-policy CR中的enabledCleanup字段为true。
driver:
  enabled: true
  enabledCleanup: true

集群中使用HPRE加速

HPRE设备资源

KAE Device Plugin（HPRE），会将节点上的KAE HPRE设备作为openfuyao.com/kae.hpre资源上报给kubelet，可通过如下命令查看集群节点上设备数量信息：

kubectl describe nodes <nodeName>

输出示例

Allocatable:
  cpu:                8
  ephemeral-storage:  35858792389
  hugepages-1Gi:      0
  hugepages-2Mi:      0
  hugepages-32Mi:     0
  hugepages-64Ki:     0
  memory:             16005200Ki
  openfuyao.com/kae.hpre: 2   #check here
  pods:               110

上述输出说明此节点上有2个HPRE设备。

工作负载配置

当前KAE HPRE加解密支持OpenSSL 1.1.1.1x版本非对称加解密。针对集群中使用OpenSSL 1.1.1.1x版本加解密的服务可以做如下配置：

编辑集群中需要使用KAE加速在工作负载如nginx_deployment.yaml：
```
kubectl edit deployments nginx_deployment -n <namespace>
```

添加resources字段，添加对KAE的资源请求：

resources:
  requests:
    openfuyao.com/kae.hpre: 1

挂载openssl配置文件到容器镜像：

  volumeMounts:
    - name: openssl-conf
      mountPath: /<container_path>/openssl.cnf
volumes:
  - name: openssl-conf
    hostPath:
    path: /<host_path>/openssl.cnf

/<host_path>为配置文件宿主机路径，/<container_path>为容器内路径。

openssl.cnf文件内容为：

openssl_conf=openssl_def
[openssl_def]
engines=engine_section
[engine_section]
kae=kae_section
[kae_section]
engine_id=kae
dynamic_path=/usr/local/lib/engines-1.1/kae.so
KAE_CMD_ENABLE_ASYNC=1
KAE_CMD_ENABLE_SM3=1
KAE_CMD_ENABLE_SM4=1
default_algorithms=ALL
init=1

也可通过configMap方式将上述文件挂载到容器中。

设置环境变量：

env:
  - name: OPENSSL_CONF
    value: /<container_path>/openssl.cnf

保存编辑内容，待Pod重新调度后生效。

特性介绍​

应用场景​

能力范围​

亮点特征​

实现原理​

与相关特性的关系​

Operator的安全上下文​

安装​

前提条件​

开始安装​

openFuyao平台​

通用场景​

安装步骤​

常见定制选项 ​

常见部署场景 ​

指定运算符命名空间​

阻止在某些节点上安装KAE驱动程序​

预安装KAE驱动程序​

运行自定义镜像​

升级​

手动升级CRD​

使用Helm Hook自动升级CRD​

KAE Policy CR更新​

卸载​

集群中使用HPRE加速​

HPRE设备资源​

工作负载配置​

特性介绍

应用场景

能力范围

亮点特征

实现原理

与相关特性的关系

Operator的安全上下文

安装

前提条件

开始安装

openFuyao平台

通用场景

安装步骤

常见定制选项

常见部署场景

指定运算符命名空间

阻止在某些节点上安装KAE驱动程序

预安装KAE驱动程序

运行自定义镜像

升级

手动升级CRD

使用Helm Hook自动升级CRD

KAE Policy CR更新

卸载

集群中使用HPRE加速

HPRE设备资源

工作负载配置